The AFPSession class provides a C++ interface to the Appletalk Filing Protocols (AFP) as documented in chapter thirteen of Inside AppleTalk. Each of the classes' methods corresponds to an AFP call. This class is useful because currently, in order to use the AFP protocol, a programmer must be very familiar with the Macintosh networking interface as implemented by the Mac toolbox. This requires knowing about param blocks and a few other poorly documented details, not a trivial matter. For example, one needs to know that the ioRefNum refers to the XPPRefNum obtained from the OpenXPP call. In any case, none of these implementation details are related to the AFP protocol itself. Why should a programmer write hundreds of lines of code just to make one or two AFP calls to a server? The AFPSession class addresses this problem by providing a clean, direct interface to AFP. It requires only a thorough understanding of Inside AppleTalk's chapter thirteen and some knowledge of C++. The messy details are hidden behind the curtain.
How do I use the class?
To use the class one merely creates an instance of it and then initializes. For example:
{
TAFPSession * client;
AddrBlock theAddress;
short VolID;
theAddress = FindServer( zoneName, serverName );
client = new TAFPSession;
client->ISession( theAddress );
client->LoginCleartxt( "Mars", "Martian" );
client->OpenVol( "Andromeda", "", 0x20 );
VolID = client->GetVolumeID();
client->Logout();
delete client;
}
The FindServer function does an NBP lookup to find the Server which will be used for the session. The client object is initialized with this server address. The next step is to "Logon" to the Server, and thereafter one can make any of the AFP calls. Each method returns an OSErr as its result indicating success or failure. If the call fails the error returned, as documented in Inside AppleTalk, will give an indication of the type of failure. After the session is finished one should always make the Logout call. This ensures that session variables allocated on the heap are properly disposed of.
Is there anything else I should know?
In addition to the regular AFP calls there are a few extra methods. The GetReply() method is used to retrieve a pointer to the reply block returned from the Server. No methods are provided to "decipher" this reply, however. There are also six Get calls which return data needed in subsequent AFP calls. These are the GetDirID, GetVolID, GetMapID, GetFileID, GetDTRefNum and GetOForkRefNum methods. The calls reply is only valid immediately after the corresponding AFP call. For example:
mySession->OpenDir("MyFolder");
theDirID = mySession->GetDirID();
What if I need direct access to the XPPParamBlock?
Some programmers will need direct access to the XPPParamBlock during the session. The AFPSession class provides for this contingency by using the virtual method DoAFPCommand when it is ready to send the AFP command across the network. The programmer can create a new class which inherits from AFPSession and uses its own DoAFPCommand. The XPPParamBlock pointer is passed to this method, allowing the programmer full access to the data structure including the command and reply blocks.
An example of this techniques usefulness is demonstrated in the TestSession class which inherits from AFPSession. The TestAFP MPW tool must be able to print the contents of the command block and the reply block in hexadecimal. To implement this, the DoAFPCommand method is overridden and uses the cbPtr parameter contained in the XPPParamBlock. the cbPtr points to the command block and we use the C++ Stream class to output its contents to the screen. Overriding the AFPSession class provides the programmer with the best of both worlds, high level access to the AFP protocol and low level access to the network data structures if needed.
Any shortcomings?
There are a few shortcomings in the current implementation. First, all calls are made synchronously. However, one can make calls asynchronously if one wishes simply by overriding the DoAFPCommand method. The use of asynchronous call with a threads library can potentially increase performance by several orders of magnitude. There should be very few bugs in the code. The AFPSession class is used as the core class in the LLPT 2.1 tool which in turn is used to test AFP compliance of servers. Several megabytes of AFP compliance scripts, written during the last several years, are funneled weekly through this code. The AFPSession class has proven to be very reliable and robust. In any case, suggestions are welcome so please feel free to report any problems you find.
